/*
 * Copyright (c) 2005, 2014 vacoor
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 */
package org.vacoor.nothing.web.dao;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

/**
 * CRUD DAO
 * <p/>
 * {@link #findOne(Map)}/{@link #findMany(Map)}/{@link #count(Map)}/{@link #deleteBy(Map)}
 * 参数均使用 Map, 之所以这样是为了更加灵活,
 * 允许根据不同场景为不同实现传递更多特定参数或覆盖默认的特殊
 * 参数来处理这些行为, 另外使用 mybatis 还可以避免繁琐的添加注解
 * <p/>
 * 默认, 定义了如下特殊参数:
 * {@link #FILTERS_PROP}   特殊的过滤条件集, 值为{@link org.vacoor.nothing.web.domain.Filters} 实例
 * {@link #SORT_PROP}       排序, 值为 {@link org.vacoor.nothing.web.domain.Sort} 实例
 * {@link #OFFSET_PROP}     数据结果的偏移量
 * {@link #MAX_RESULTS_PROP}    结果集大小
 * 它们可用于 {@link #findOne(Map)} {@link #findMany(Map)}, {@link #count(Map)}只可用 FILTERS_PROP
 * 其余参数均使用 key = value 进行过滤
 *
 * @author vacoor
 */
public interface CrudDao<E, ID extends Serializable> {
    String OFFSET_PROP = "_offset";
    String MAX_RESULTS_PROP = "_maxResults";
    String FILTERS_PROP = "_filters";
    String SORT_PROP = "_sort";

    E find(ID id);

    E findOne(Map<String/*prop*/, ?/*value*/> params);

    List<E> findMany(Map<String/*prop*/, ?/*value*/> params);

    int count(Map<String/*prop*/, ?/*value*/> params);

    void save(E e);

    void update(E e);

    /**
     * 删除给定对象
     * 删除前建议先判断是否存在, 给出合理提示(是否存在), 而不应该由数据库来决定删除
     * 因此这里使用被删除对象作为参数来简单限制, 但是删除时只会使用 id
     *
     * @param e
     */
    void delete(E e);

    /*- 删除前应当判断是否存在, 给出合理提示, 不应该直接由数据库来决定删除
     使用时 e = find(...) if (e != null) { do something.. delete(e); } else { do something }
    void delete(ID id);

    void deleteBy(Map<String, ?> params);
    */
}
